---
description: 'Enforce descriptions in type definitions and operations.'
---

# `require-description`

✅ The `"extends": "plugin:@graphql-eslint/schema-recommended"` property in a configuration file
enables this rule.

- Category: `Schema`
- Rule name: `@graphql-eslint/require-description`
- Requires GraphQL Schema: `false`
  [ℹ️](/docs/getting-started#extended-linting-rules-with-graphql-schema)
- Requires GraphQL Operations: `false`
  [ℹ️](/docs/getting-started#extended-linting-rules-with-siblings-operations)

{metadata.description}

## Usage Examples

### Incorrect

```graphql
# eslint @graphql-eslint/require-description: ['error', { types: true, FieldDefinition: true }]

type someTypeName {
  name: String
}
```

### Correct

```graphql
# eslint @graphql-eslint/require-description: ['error', { types: true, FieldDefinition: true }]

"""
Some type description
"""
type someTypeName {
  """
  Name description
  """
  name: String
}
```

### Correct

```graphql
# eslint @graphql-eslint/require-description: ['error', { OperationDefinition: true }]

# Create a new user
mutation createUser {
  # ...
}
```

### Correct

```graphql
# eslint @graphql-eslint/require-description: ['error', { rootField: true }]

type Mutation {
  "Create a new user"
  createUser: User
}

type User {
  name: String
}
```

### Correct

```graphql
# eslint @graphql-eslint/require-description: ['error', { ignoredSelectors: ['[type=ObjectTypeDefinition][name.value=PageInfo]', '[type=ObjectTypeDefinition][name.value=/(Connection|Edge)$/]'] }]

type FriendConnection {
  edges: [FriendEdge]
  pageInfo: PageInfo!
}
type FriendEdge {
  cursor: String!
  node: Friend!
}
type PageInfo {
  hasPreviousPage: Boolean!
  hasNextPage: Boolean!
  startCursor: String
  endCursor: String
}
```

## Config Schema

The schema defines the following properties:

### `types` (boolean, enum)

Includes:

- `ObjectTypeDefinition`
- `InterfaceTypeDefinition`
- `EnumTypeDefinition`
- `ScalarTypeDefinition`
- `InputObjectTypeDefinition`
- `UnionTypeDefinition`

This element must be one of the following enum values:

- `true`

### `rootField` (boolean, enum)

Definitions within `Query`, `Mutation`, and `Subscription` root types.

This element must be one of the following enum values:

- `true`

### `ignoredSelectors` (array)

Ignore specific selectors

> [!TIP]
>
> These fields are defined by ESLint
> [`selectors`](https://eslint.org/docs/developer-guide/selectors). Paste or drop code into the
> editor in [ASTExplorer](https://astexplorer.net) and inspect the generated AST to compose your
> selector.

The object is an array with all elements of the type `string`.

Additional restrictions:

- Minimum items: `1`
- Unique items: `true`

### `DirectiveDefinition` (boolean)

> [!NOTE]
>
> Read more about this kind on
> [spec.graphql.org](https://spec.graphql.org/October2021/#DirectiveDefinition).

### `EnumTypeDefinition` (boolean)

> [!NOTE]
>
> Read more about this kind on
> [spec.graphql.org](https://spec.graphql.org/October2021/#EnumTypeDefinition).

### `EnumValueDefinition` (boolean)

> [!NOTE]
>
> Read more about this kind on
> [spec.graphql.org](https://spec.graphql.org/October2021/#EnumValueDefinition).

### `FieldDefinition` (boolean)

> [!NOTE]
>
> Read more about this kind on
> [spec.graphql.org](https://spec.graphql.org/October2021/#FieldDefinition).

### `InputObjectTypeDefinition` (boolean)

> [!NOTE]
>
> Read more about this kind on
> [spec.graphql.org](https://spec.graphql.org/October2021/#InputObjectTypeDefinition).

### `InputValueDefinition` (boolean)

> [!NOTE]
>
> Read more about this kind on
> [spec.graphql.org](https://spec.graphql.org/October2021/#InputValueDefinition).

### `InterfaceTypeDefinition` (boolean)

> [!NOTE]
>
> Read more about this kind on
> [spec.graphql.org](https://spec.graphql.org/October2021/#InterfaceTypeDefinition).

### `ObjectTypeDefinition` (boolean)

> [!NOTE]
>
> Read more about this kind on
> [spec.graphql.org](https://spec.graphql.org/October2021/#ObjectTypeDefinition).

### `OperationDefinition` (boolean)

> [!NOTE]
>
> Read more about this kind on
> [spec.graphql.org](https://spec.graphql.org/October2021/#OperationDefinition).

> [!WARNING]
>
> You must use only comment syntax `#` and not description syntax `"""` or `"`.

### `ScalarTypeDefinition` (boolean)

> [!NOTE]
>
> Read more about this kind on
> [spec.graphql.org](https://spec.graphql.org/October2021/#ScalarTypeDefinition).

### `UnionTypeDefinition` (boolean)

> [!NOTE]
>
> Read more about this kind on
> [spec.graphql.org](https://spec.graphql.org/October2021/#UnionTypeDefinition).

## Resources

- [Rule source](https://github.com/dimaMachina/graphql-eslint/tree/master/packages/plugin/src/rules/require-description.ts)
- [Test source](https://github.com/dimaMachina/graphql-eslint/tree/master/packages/plugin/__tests__/require-description.spec.ts)
